Developer CD Series 1995 June: Reference Library/Dev.CD Jun 95/Dev.CD Jun 95.toast/What's New?/New System Software Extensions/QuickDraw 3D ß/Programming/Interfaces/QD3DView.h

C/C++ Source or Header | 1995-04-04 | 12.2 KB | 395 lines | [TEXT/MPS ]

/******************************************************************************
 **                                                                          **
 **     Module:        QD3DView.h                                                 **
 **                                                                          **
 **                                                                          **
 **     Purpose:     View types and routines                                     **
 **                                                                          **
 **                                                                          **
 **     Copyright (C) 1992-1995 Apple Computer, Inc.  All rights reserved.     **
 **                                                                          **
 **                                                                          **
 *****************************************************************************/
#ifndef QD3DView_h
#define QD3DView_h

#if PRAGMA_ONCE
    #pragma once
#endif

#include "QD3DStyle.h"
#include "QD3DSet.h"

#ifdef __cplusplus
extern "C" {
#endif    /* __cplusplus */


/******************************************************************************
 **                                                                             **
 **                        View Type Definitions                                 **
 **                                                                             **
 *****************************************************************************/

typedef enum TQ3ViewStatus {
    kQ3ViewStatusDone,
    kQ3ViewStatusRetraverse,
    kQ3ViewStatusError,
    kQ3ViewStatusCancelled
} TQ3ViewStatus;


/******************************************************************************
 **                                                                             **
 **                        Default Attribute Set                                 **
 **                                                                             **
 *****************************************************************************/

#define kQ3ViewDefaultAmbientCoefficient    1.0
#define kQ3ViewDefaultDiffuseColor            0.5, 0.5, 0.5
#define kQ3ViewDefaultSpecularColor            0.5, 0.5, 0.5
#define kQ3ViewDefaultSpecularControl        4.0
#define kQ3ViewDefaultEmittedColor            0.0, 0.0, 0.0
#define kQ3ViewDefaultTransparency            1.0, 1.0, 1.0

#define kQ3ViewDefaultSubdivisionMethod        kQ3SubdivisionMethodConstant
#define kQ3ViewDefaultSubdivisionC1            10.0
#define kQ3ViewDefaultSubdivisionC2            10.0

/******************************************************************************
 **                                                                             **
 **                            View Routines                                      **
 **                                                                             **
 *****************************************************************************/

EXPORT TQ3ViewObject Q3View_New(
    void);

#if defined(ESCHER_VER_15) && ESCHER_VER_15

EXPORT TQ3ObjectType Q3View_GetType(
    TQ3ViewObject        view);

#endif  /*  ESCHER_VER_15  */

/******************************************************************************
 **                                                                             **
 **                        View Rendering routines                                 **
 **                                                                             **
 *****************************************************************************/

EXPORT TQ3Status Q3View_SetRendererByType(
    TQ3ViewObject         view,
    TQ3ObjectType         type);

EXPORT TQ3Status Q3View_SetRenderer(
    TQ3ViewObject         view,
    TQ3RendererObject    renderer);

EXPORT TQ3Status Q3View_GetRenderer(
    TQ3ViewObject        view,
    TQ3RendererObject    *renderer);

EXPORT TQ3Status Q3View_StartRendering(
    TQ3ViewObject         view);

EXPORT TQ3ViewStatus Q3View_EndRendering(
    TQ3ViewObject         view);

EXPORT TQ3Status Q3View_CancelRendering(
    TQ3ViewObject        view);

/******************************************************************************
 **                                                                             **
 **                        View/Bounds/Pick routines                             **
 **                                                                             **
 *****************************************************************************/

EXPORT TQ3Status Q3View_StartBoundingBox(
    TQ3ViewObject        view,
    TQ3ComputeBounds    computeBounds);

EXPORT TQ3ViewStatus Q3View_EndBoundingBox(
    TQ3ViewObject        view,
    TQ3BoundingBox        *result);

EXPORT TQ3Status Q3View_StartBoundingSphere(
    TQ3ViewObject        view,
    TQ3ComputeBounds    computeBounds);

EXPORT TQ3ViewStatus Q3View_EndBoundingSphere(
    TQ3ViewObject        view,
    TQ3BoundingSphere    *result);

EXPORT TQ3Status Q3View_StartPicking(
    TQ3ViewObject        view,
    TQ3PickObject        pick);

EXPORT TQ3ViewStatus Q3View_EndPicking(
    TQ3ViewObject        view);

/******************************************************************************
 **                                                                             **
 **                            View/Camera routines                             **
 **                                                                             **
 *****************************************************************************/

EXPORT TQ3Status Q3View_GetCamera(
    TQ3ViewObject        view,
    TQ3CameraObject        *camera);

EXPORT TQ3Status Q3View_SetCamera(
    TQ3ViewObject        view,
    TQ3CameraObject        camera);

#if defined(ESCHER_VER_15) && ESCHER_VER_15
/******************************************************************************
 **                                                                             **
 **                            View/Shader routines                             **
 **                                                                             **
 *****************************************************************************/

EXPORT TQ3Status Q3View_SetBackgroundShader(
    TQ3ViewObject        view,
    TQ3ShaderObject        backgroundShader);

EXPORT TQ3Status Q3View_GetBackgroundShader(
    TQ3ViewObject        view,
    TQ3ShaderObject        *backgroundShader);

EXPORT TQ3Status Q3View_SetAtmosphericShader(
    TQ3ViewObject        view,
    TQ3ShaderObject        atmospheric);

EXPORT TQ3Status Q3View_GetAtmosphericShader(
    TQ3ViewObject        view,
    TQ3ShaderObject        *atmospheric);

EXPORT TQ3Status Q3View_SetForegroundShader(
    TQ3ViewObject        view,
    TQ3ShaderObject        imagePlaneShader);

EXPORT TQ3Status Q3View_GetForegroundShader(
    TQ3ViewObject        view,
    TQ3ShaderObject        *imagePlaneShader);

#endif  /*  ESCHER_VER_15  */

/******************************************************************************
 **                                                                             **
 **                            View/Lights routines                             **
 **                                                                             **
 *****************************************************************************/

EXPORT TQ3Status Q3View_SetLightGroup(
    TQ3ViewObject        view,
    TQ3GroupObject        lightGroup);

EXPORT TQ3Status Q3View_GetLightGroup(
    TQ3ViewObject        view,
    TQ3GroupObject        *lightGroup);

/******************************************************************************
 **                                                                             **
 **        Idle Method                                                             **
 **                                                                             **
 **        These allow the application to register callback routines which will **
 **        be called by the view during especially long operations.             **
 **                                                                             **
 **        These are used to interrupt long renderings or traversals.  Inside   **
 **        the idler callback the application can check for command-period or      **
 **        whatever else they may be using to let the user interrupt rendering. **
 **                                                                             **
 **        It is NOT LEGAL to call QD3D routines except Q3View_CancelRendering    **
 **        inside an idler callback.                                             **
 **        (Actually, we don't check for this.  But don't try it.  We'll          **
 **        blow up!)                                                             **
 **                                                                             **
 **        Q3View_SetIdleMethod registers a callback that can be called         **
 **        by the system during rendering.  Unfortunately there is no way yet     **
 **        to set timer intervals when you want to be called.  Basically, it is **
 **        up to the application's idler callback to check clocks to see if you **
 **        were called back only a millisecond ago or an hour ago!                 **
 **                                                                             **
 *****************************************************************************/

typedef void (*TQ3ViewIdleMethod)(
    TQ3ViewObject        view,
    const void            *idlerData);

EXPORT TQ3Status Q3View_SetIdleMethod(
    TQ3ViewObject        view,
    TQ3ViewIdleMethod    idleMethod,
    const void             *idleData);


/******************************************************************************
 **                                                                             **
 **                            Push/Pop routines                                 **
 **                                                                             **
 *****************************************************************************/

EXPORT TQ3Status Q3Push_Submit(
    TQ3ViewObject     view);

EXPORT TQ3Status Q3Pop_Submit(
    TQ3ViewObject     view);


/******************************************************************************
 **                                                                             **
 **        Check if bounding box is visible in the viewing frustum.  Transforms **
 **        the bbox by the current local_to_world transformation matrix and     **
 **        does a clip test to see if it lies in the viewing frustum.             **
 **        This can be used by applications to cull out large chunks of scenes     **
 **        that are not going to be visible.                                     **
 **                                                                             **
 **        The default implementation is to always return kQ3True.  Renderers     **
 **        may override this routine however to do the checking.                 **
 **                                                                             **
 *****************************************************************************/

EXPORT TQ3Boolean Q3View_IsBoundingBoxVisible(
    TQ3ViewObject            view,
    const TQ3BoundingBox    *bbox);


/******************************************************************************
 **                                                                             **
 **                            DrawContext routines                             **
 **                                                                             **
 *****************************************************************************/

EXPORT TQ3Status Q3View_SetDrawContext(
    TQ3ViewObject             view,
    TQ3DrawContextObject    drawContext);

EXPORT TQ3Status Q3View_GetDrawContext(
    TQ3ViewObject             view,
    TQ3DrawContextObject    *drawContext);


/******************************************************************************
 **                                                                             **
 **                            Graphics State routines                             **
 **                                                                             **
 ** The graphics state routines can only be called while rendering (ie. in     **
 ** between calls to start and end rendering calls).  If they are called     **
 ** outside of a rendering loop, they will return with error.                 **
 **                                                                             **
 *****************************************************************************/

/******************************************************************************
 **                                                                             **
 **                            Transform routines                                  **
 **                                                                             **
 *****************************************************************************/

EXPORT TQ3Status Q3View_GetLocalToWorldMatrixState(
    TQ3ViewObject        view,
    TQ3Matrix4x4        *matrix);

EXPORT TQ3Status Q3View_GetWorldToFrustumMatrixState(
    TQ3ViewObject        view,
    TQ3Matrix4x4        *matrix);

EXPORT TQ3Status Q3View_GetFrustumToWindowMatrixState(
    TQ3ViewObject        view,
    TQ3Matrix4x4        *matrix);


/******************************************************************************
 **                                                                             **
 **                            Style state routines                             **
 **                                                                             **
 *****************************************************************************/

EXPORT TQ3Status Q3View_GetBackfacingStyleState(
    TQ3ViewObject            view,
    TQ3BackfacingStyle        *backfacingStyle);

EXPORT TQ3Status Q3View_GetInterpolationStyleState(
    TQ3ViewObject            view,
    TQ3InterpolationStyle    *interpolationType);

EXPORT TQ3Status Q3View_GetFillStyleState(
    TQ3ViewObject            view,
    TQ3FillStyle            *fillStyle);

EXPORT TQ3Status Q3View_GetHighlightStyleState(
    TQ3ViewObject            view,
    TQ3AttributeSet            *highlightStyle);

EXPORT TQ3Status Q3View_GetSubdivisionStyleState(
    TQ3ViewObject            view,
    TQ3SubdivisionStyleData    *subdivisionStyle);

EXPORT TQ3Status Q3View_GetOrientationStyleState(
    TQ3ViewObject            view,
    TQ3OrientationStyle        *fontFacingDirectionStyle);

EXPORT TQ3Status Q3View_GetReceiveShadowsStyleState(
    TQ3ViewObject            view,
    TQ3Boolean                *receives);

EXPORT TQ3Status Q3View_GetPickIDStyleState(
    TQ3ViewObject            view,
    unsigned long            *pickIDStyle);

EXPORT TQ3Status Q3View_GetPickPartsStyleState(
    TQ3ViewObject            view,
    TQ3PickParts            *pickPartsStyle);

/******************************************************************************
 **                                                                             **
 **                        Attribute state routines                             **
 **                                                                             **
 *****************************************************************************/

EXPORT TQ3Status Q3View_GetDefaultAttributeSet(
    TQ3ViewObject        view,
    TQ3AttributeSet        *attributeSet);

EXPORT TQ3Status Q3View_SetDefaultAttributeSet(
    TQ3ViewObject        view,
    TQ3AttributeSet        attributeSet);


EXPORT TQ3Status Q3View_GetAttributeSetState(
    TQ3ViewObject         view,
    TQ3AttributeSet        *attributeSet);

EXPORT TQ3Status Q3View_GetAttributeState(
    TQ3ViewObject         view,
    TQ3AttributeType    attributeType,
    void                *data);

#if defined(ESCHER_VER_15) && ESCHER_VER_15
/******************************************************************************
 **                                                                             **
 **                            Cache Routines                                      **
 **                                                                             **
 *****************************************************************************/

EXPORT TQ3Status Q3View_StartRenderingCache(
    TQ3ViewObject        view,
    unsigned long        id);

EXPORT TQ3Status Q3View_IsRenderingCacheValid(
    TQ3ViewObject        view,
    unsigned long        id,
    TQ3Boolean            *isValid);

EXPORT TQ3Status Q3View_ClearRenderingCache(
    TQ3ViewObject        view,
    unsigned long        id);


#endif    /*  ESCHER_VER_15  */

#ifdef __cplusplus
}
#endif    /* __cplusplus */

#endif  /*  QD3DView_h  */